home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_libproplist.idb / usr / freeware / include / proplist.h.z / proplist.h
Encoding:
C/C++ Source or Header  |  1999-07-16  |  4.9 KB  |  170 lines
  1. /* proplist.h: This is -*- c -*-
  2.  
  3.    Copyright (c) 1997 Bjoern Giesler <giesler@ira.uka.de>
  4.    libPropList and this file are subject to the GNU Library Public License
  5.    (LPL). You should have received a copy of that license; it's in the 
  6.    file COPYING.LIB.
  7.    
  8.    Interface declaration for the property-list handling library. This
  9.    library allows plain C programs to use (read and write)
  10.    GNUstep-style property lists. It defines the opaque data type
  11.    proplist_t. An element of type proplist_t can be a string, an
  12.    array, a dictionary or a data object.
  13.  
  14.    */
  15.  
  16. #ifndef PROPLIST_H
  17. #define PROPLIST_H
  18.  
  19. #ifndef BOOL
  20. #define BOOL int
  21. #endif /* !def BOOL */
  22. #ifndef YES
  23. #define YES 1
  24. #define NO 0
  25. #endif /* !def YES */
  26.  
  27. typedef void *proplist_t;
  28.  
  29. typedef void (*plcallback_t)(void);
  30.  
  31.  
  32. /*
  33.  * Vanilla file-handling stuff
  34.  */
  35.  
  36. /* Return a pointer to a proplist structure if successful, NULL otherwise */
  37. proplist_t PLGetProplistWithDescription(const char *description);
  38.  
  39. /* Return a pointer to a proplist structure if successful, NULL otherwise */
  40. proplist_t PLGetProplistWithPath(const char *filename);
  41.  
  42. /* Synchronize the proplist with the file: Returns NO on error */
  43. BOOL PLSynchronize(proplist_t pl);
  44.  
  45. /* Write out to a file. Uses temporary file if atomically==YES. Returns
  46.    NO on error */ 
  47. BOOL PLSave(proplist_t pl, BOOL atomically);
  48.  
  49. /* Get the file name for the property list */
  50. proplist_t PLSetFilename(proplist_t pl, proplist_t filename);
  51.  
  52. /* Get the file name, or NULL if there isn't any */
  53. proplist_t PLGetFilename(proplist_t pl);
  54.  
  55. /*
  56.  * Talking to the daemon
  57.  */
  58.  
  59. /* Get an array containing all registered domain names. */
  60. proplist_t PLGetDomainNames();
  61.  
  62. /* Get the named domain from the daemon. If callback is non-NULL, it
  63.    specifies a function to be called whenever the domain is changed. */
  64. proplist_t PLGetDomain(proplist_t name);
  65.  
  66. /* Set the specified domain. If kickme is NO, a callback function the
  67.    program has registered for this domain will not be called. */
  68. proplist_t PLSetDomain(proplist_t name, proplist_t value,
  69.          BOOL kickme);
  70.  
  71. /* See above. */
  72. proplist_t PLDeleteDomain(proplist_t name, BOOL kickme);
  73.  
  74. /* Returns the specified domain, and registers callback to be called
  75.    whenever domain is changed. Returns name. */
  76. proplist_t PLRegister(proplist_t name, plcallback_t callback);
  77.  
  78. /* Unregisters callback entries for name, or all callback entries if
  79.    name is NULL. Returns name. */
  80. proplist_t PLUnregister(proplist_t name);
  81.  
  82. /*
  83.  * Test if the proplist is of a certain type
  84.  */
  85. BOOL PLIsString(proplist_t pl);
  86. BOOL PLIsData(proplist_t pl);
  87. BOOL PLIsArray(proplist_t pl);
  88. BOOL PLIsDictionary(proplist_t pl);
  89. BOOL PLIsSimple(proplist_t pl); /* YES if pl is string or data */
  90. BOOL PLIsCompound(proplist_t pl); /* YES if pl is array or dictionary */
  91.  
  92. /* Returns a reference. Don't free it! */
  93. char *PLGetString(proplist_t pl); 
  94.  
  95. /*
  96.  * Values of simple types. Note that all these return copies; free the
  97.  * return value after you're done.
  98.  */
  99. char *PLGetStringDescription(proplist_t pl);
  100. char *PLGetDataDescription(proplist_t pl);
  101. unsigned int PLGetDataLength(proplist_t pl);
  102. unsigned char *PLGetDataBytes(proplist_t pl);
  103.  
  104. /*
  105.  * The description in proplist format. Free the return value.
  106.  */
  107. char *PLGetDescriptionIndent(proplist_t pl, unsigned int level);
  108. char *PLGetDescription(proplist_t pl);
  109.  
  110.  
  111. /*
  112.  * Descending into compound types. None of these return copies.
  113.  */
  114. unsigned int PLGetNumberOfElements(proplist_t pl);
  115. proplist_t PLGetArrayElement(proplist_t pl, unsigned int index);
  116. proplist_t PLGetAllDictionaryKeys(proplist_t pl); /* returns an array */
  117. proplist_t PLGetDictionaryEntry(proplist_t pl, proplist_t key);
  118.  
  119. /*
  120.  * Getting the container
  121.  */
  122. proplist_t PLGetContainer(proplist_t pl);
  123.  
  124. /*
  125.  * Creating simple types
  126.  */
  127. proplist_t PLMakeString(char *bytes);
  128. proplist_t PLMakeData(unsigned char *data, unsigned int length);
  129.  
  130. /*
  131.  * Creating/Changing compound types
  132.  */
  133. /* Make an array from the given elements. List must be NULL-terminated. */
  134. proplist_t PLMakeArrayFromElements(proplist_t pl, ...);
  135. /* returns NULL if index out of bounds */
  136. proplist_t PLInsertArrayElement(proplist_t array, proplist_t pl,
  137.                 unsigned int index);
  138. proplist_t PLRemoveArrayElement(proplist_t array,
  139.                 unsigned int index);
  140. proplist_t PLAppendArrayElement(proplist_t array, proplist_t pl);
  141.  
  142. proplist_t PLMakeDictionaryFromEntries(proplist_t key, proplist_t value,
  143.                        ...);
  144. proplist_t PLInsertDictionaryEntry(proplist_t dict, proplist_t key,
  145.                    proplist_t value);
  146. proplist_t PLRemoveDictionaryEntry(proplist_t dict, proplist_t key);
  147. /* Changes only dest. Copies entries from source. */
  148. proplist_t PLMergeDictionaries(proplist_t dest, proplist_t source);
  149.  
  150. /*
  151.  * Destroying and Copying
  152.  */
  153.  
  154. proplist_t PLShallowCopy(proplist_t pl);
  155. proplist_t PLDeepCopy(proplist_t pl);
  156. void PLRelease(proplist_t pl);
  157. proplist_t PLRetain(proplist_t pl);
  158.  
  159. /*
  160.  * Comparing
  161.  */
  162.  
  163. BOOL PLIsEqual(proplist_t pl1, proplist_t pl2);
  164. void PLSetStringCmpHook(BOOL(*fn)(proplist_t, proplist_t));
  165.  
  166.  
  167. #endif /* !def PROPLIST_H */
  168.  
  169.  
  170.